/*
 * Copyright 2002-2016 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.config;

import org.springframework.beans.BeansException;

/**
 * Allows for custom modification of an application context's bean definitions,
 * adapting the bean property values of the context's underlying bean factory.
 *
 * 允许应用上下文的 b.d. 进行自定义修改，以适配上下文中的 bean factory 的 bean 属性值。
 *
 * <p>Application contexts can auto-detect BeanFactoryPostProcessor beans in
 * their bean definitions and apply them before any other beans get created.
 *
 * 应用上下文可以自动监测 b.d. 中的 BeanFactoryPostProcessor 并且 在任何其他的 bean
 * 创建之前应用他们。
 *
 * <p>Useful for custom config files targeted at system administrators that
 * override bean properties configured in the application context.
 *
 * 对于针对系统管理员的自定义配置文件非常有用，系统管理员可以覆盖在应用程序上下文中配置的 bean 属性。
 *
 * <p>See PropertyResourceConfigurer and its concrete implementations
 * for out-of-the-box solutions that address such configuration needs.
 *
 * 满足我们的需求（address our needs）的开箱即用（out-of-the-box）的解决方案
 * 请参考 PropertyResourceConfigurer 以及 它的实现。
 *
 * <p>A BeanFactoryPostProcessor may interact with and modify bean
 * definitions, but never bean instances. Doing so may cause premature bean
 * instantiation, violating the container and causing unintended side-effects.
 * If bean instance interaction is required, consider implementing
 * {@link BeanPostProcessor} instead.
 *
 * 一个 BeanFactoryPostProcessor 可以与 b.d. 交互并且修改 b.d. ，
 * 但是绝不能与 bean 实例交互！
 * 注意：一旦将 BeanFactoryPostProcessor 与 bean 实例进行交互，可能会导致过早的 bean 初始化，
 * 违反容器的流程，并且导致 意外的（unintended） 单边影响。
 * 如果需要 bean 实例的交互，请考虑实现 {@link BeanPostProcessor}
 *
 * 官方的注解很详细，可以得出：
 * 1. BeanFactoryPostProcessor 是用来与 b.d. 交互 + 修改的；
 * 2. 应用上下文可以对 BeanFactoryPostProcessor 自动监测，并且在 bean 实例被创建之前应用；
 * 3. BeanFactoryPostProcessor 与 BeanPostProcessor 的区别！
 * 		一个是 b.d. 交互；一个是与 bean 实例交互。
 *
 * @author Juergen Hoeller
 * @since 06.07.2003
 * @see BeanPostProcessor
 * @see PropertyResourceConfigurer
 */
@FunctionalInterface
public interface BeanFactoryPostProcessor {

	/**
	 * Modify the application context's internal bean factory after its standard
	 * initialization. All bean definitions will have been loaded, but no beans
	 * will have been instantiated yet. This allows for overriding or adding
	 * properties even to eager-initializing beans.
	 *
	 * 在 应用上下文的标准初始化以后，修改应用上下文内部的 bean factory .
	 * 所有的 b.d. 会被加载，但是目前所有的 bean 都没有被初始化。
	 * 本方法允许 对 b.d. 重写或者添加属性，甚至对于 饿汉式初始化的 beans.
	 *
	 * 从官方注释可得：
	 * 1.本方法的作用是：修改上下文内部的 bean factory;
	 * 2.时间发生在：上下文完成了初始化，所有的 b.d. 都被加载，但是没有 bean 被初始化；
	 * 		同时，也是在后置处理器最开始的时候，先处理自定义的处理器！
	 * 3.一般用于 重写 + 添加 b.d.的属性
	 *
	 * @param beanFactory the bean factory used by the application context
	 * @throws org.springframework.beans.BeansException in case of errors
	 */
	void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException;

}
